<?php
// $Id: Workspace.interface.php 73 2007-02-12 03:45:43Z tswicegood $

/**
 * This file contains {@link Workspace} which is part of the PHP Content Repository
 * (phpCR), a derivative of the Java Content Repository JSR-170,  and is 
 * licensed under the Apache License, Version 2.0.
 *
 * This file is based on the b created for
 * {@link http://www.jcp.org/en/jsr/detail?id=170 JSR-170}
 *
 * @author Travis Swicegood <travis@domain51.net>
 * @copyright PHP Code Copyright &copy; 2004-2005, Domain51, United States
 * @copyright Original Java and Documentation 
 *  Copyright &copy; 2002-2004, Day Management AG, Switerland
 * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, 
 *      Version 2.0
 * @package phpContentRepository
 */


/**
 * Load the {@link phpCR} library file(s)
 */ 
require_once(dirname(__FILE__) . '/phpCR.library.php');


/**
 * Represents a view onto the the content repository associated with a 
 * particular {@link Ticket}.
 *
 * Acquired by calling {@link Ticket::getWorkspace()}.
 *
 * @author PHP - Travis Swicegood <travis@domain51.net>
 * @copyright Copyright &copy; 2004-2005, Domain51
 * @package phpContentRepository
 */
interface Workspace
{

   /**
    * Returns the {@link Ticket} object through which this {@link Workspace}
    * object was acquired.
    *
    * @return object
    *   A {@link Ticket} object.
    */
    public function getTicket();
    
    
   /**
    * Copies the node at $srcAbsPath to the new location at
    * $destAbsPath.
    *
    * If $shallow is TRUE then only the node at
    * $srcAbsPath and its properties (but not its child nodes) is
    * copied to the new location, otherwise its entire subtree is copied. 
    *
    * If succesful, the parent of the new node at $destAbsPath is 
    * "saved" (i.e. the change is persisted immediately, there is no need to
    * call{@link Node::save()}).
    *
    * Throws an exception if there is already an item at 
    * $destAbsPath, or if some other constraint (access, node type,
    * system-level) is violated.
    *
    * To copy a {@link Node} to another {@link Workspace}, use {@link clone()}.
    *
    * @param string
    *   The path of the {@link Node} to be copied.
    * @param string
    *   The location to which the {@link Node} at $srcAbsPath is
    *   to be copied.
    * @param bool
    *   If TRUE only the {@link Node} at $srcAbsPath 
    *   and its properties are copied, otherwise the source {@link Node} and 
    *   its entire subtree is copied.
    *
    * @see clone()
    *
    * @throws {@link ConstraintViolationException}
    *   If the copy would violate a {@link NodeType} or other constraint.
    * @throws {@link AccessDeniedException}
    *   If the current {@link Ticket} (i.e. the {@link Ticket} that was used to
    *   aqcuire this {@link Workspace} object) does not have sufficient access 
    *   rights to complete the operation.
    * @throws {@link PathNotFoundException}
    *   If the {@link Node} at $srcAbsPath or the parent of the 
    *   new {@link Node} at $destAbsPath does not exist.
    * @throws {@link ItemExistsException}
    *   If a {@link Node} or {@link Property} already exists at 
    *   $destAbsPath.
    * @throws {@link ActionVetoedException}
    *   If a {@link VetoableEventListener} vetoes one of the changes being 
    *   saved.
    * @throws {@link RepositoryException}
    *   If another error occurs.
    */
    public function copy($srcAbsPath, $destAbsPath, $shallow);
    
    
   /**
    * Copies the subtree (or {@link Node} and its {@link Property}s if 
    * $shallow is TRUE) at $srcAbsPath to the new location at $destAbsPath in 
    * the specified {@link Workspace} - $destWorkspace.
    *
    * To copy a {@link Node} within the same {@link Workspace}, use 
    * {@link copy()}.
    *
    * <b>PHP Note</b>: This should be called, clone(), but due to 
    * {@link http://www.php.net/manual/en/language.oop5.cloning.php clone keyword}
    * present in PHP5, 'clone' can't be used as method name.
    *
    * @param string
    *   The path of the {@link Node} to be copied.
    * @param string
    *   The location to which the {@link Node} at $srcAbsPath is
    *   to be copied.
    * @param string
    *   The destination {@link Workspace} this is to be copied to.
    * @param bool
    *   If TRUE only the {@link Node} at $srcAbsPath 
    *   and its properties are copied, otherwise the source {@link Node} and 
    *   its entire subtree is copied.
    *
    * @see copy()
    *
    * @throws {@link ConstraintViolationException}
    *   If the copy would violate a {@link NodeType} or other constraint.
    * @throws {@link AccessDeniedException}
    *   If the current {@link Ticket} (i.e. the {@link Ticket} that was used to
    *   aqcuire this {@link Workspace} object) does not have sufficient access 
    *   rights to complete the operation.
    * @throws {@link PathNotFoundException}
    *   If the {@link Node} at $srcAbsPath or the parent of the 
    *   new {@link Node} at $destAbsPath does not exist.
    * @throws {@link ItemExistsException}
    *   If a {@link Node} or {@link Property} already exists at 
    *   $destAbsPath.
    * @throws {@link ActionVetoedException}
    *   If a {@link VetoableEventListener} vetoes one of the changes being 
    *   saved.
    * @throws {@link RepositoryException}
    *   If another error occurs.
    */
    public function clone_($srcAbsPath, $destAbsPath, $destWorkspace, $shallow);
    
    
   /**
    * Moves the {@link Node} at $srcAbsPath (and its entire 
    * subtree) to the new location at $destAbsPath.
    *
    * Throws an exception if there is already an item at 
    * $destAbsPath, or if some other constraint (access, node type,
    * system-level) is violated.
    *
    * If succesful, the parent of the new {@link Node} at 
    * $destAbsPath is "saved" (i.e. the change is persisted 
    * immediately as is the parent of the moved {@link Node} at its original 
    * location, there is no need to call {@link Node::save()}).
    *
    * @param string 
    *   The path of the {@link Node} to be moved.
    * @param string
    *   The location to which the {@link Node} at $srcAbsPath is
    *   to be moved.
    *
    * @throws {@link ConstraintViolationException} 
    *   If the move would violate a node type or other constraint.
    * @throws {@link AccessDeniedException}
    *   If the current {@link Ticket} (i.e. the {@link Ticket} that was used to
    *   aqcuire this {@link Workspace} object) does not have sufficient access 
    *   rights to complete the operation.
    * @throws {@link PathNotFoundException}
    *   If the {@link Node} at $srcAbsPath or the parent of the 
    *   new {@link Node} at $destAbsPath does not exist.
    * @throws {@link ItemExistsException}
    *   If a {@link Node} or {@link Property} already exists at 
    *   $destAbsPath.
    * @throws {@link ActionVetoedException}
    *   If a {@link VetoableEventListener} vetoes one of the changes being 
    *   saved.
    * @throws {@link RepositoryException}
    *   If another error occurs.
    */
    public function move($srcAbsPath, $destAbsPath);
    
    
   /**
    * Gets the {@link QueryManager}.
    *
    * Gets the {@link QueryManager} through which searching is done.
    *
    * @return object 
    *   The {@link QueryManager} object.
    */
    public function getQueryManager();
    
    
   /**
    * Returns the {@link NamespaceRegistry} object, which is used to set the 
    * mapping between namespace prefixes and URIs.
    *
    * @return object
    *   The {@link NamespaceRegistry} object.
    */
    public function getNamespaceRegistry();
    
    
   /**
    * Gets the {@link NodeTypeManager} object.
    *
    * Returns the {@link NodeTypeManager} through which node type
    * information can be queried.
    *
    * @return object
    *   A {@link NodeTypeManager} object.
    */
    public function getNodeTypeManager();
    
    
   /**
    * Returns the {@link AccessManager} object. (Level 2)
    *
    * Level 1:
    *
    * Always throws an {@link UnsupportedRepositoryOperationException}
    * since locking is not supported in level 1.
    *
    * Level 2:
    *
    * Always returns an {@link AccessManager} object.
    *
    * @return object
    *   An AccessManager object.
    *
    * @throws {@link UnsupportedRepositoryOperationException}
    *   In level 1: Always.  In level 2: Never.
    */
    public function getAccessManager();
    
    
   /**
    * Returns the {@link LockCapabilities} object. (Level 2)
    *
    * Locking is an optional.  When it is supported, this should return a
    * {@link LockCapabilities} object; if not, it should throw an
    * {@link UnsupportedRepositoryOperationException}.
    *
    * Level 1:
    *
    * Always throws an {@link UnsupportedRepositoryOperationException}
    * since locking is not supported in level 1.
    *
    * Level 2:
    *
    * If locking is supported, returns the {@link LockCapabilities} object 
    * through which dynamic discovery of supported locking functionality is
    * provided. If locking is not supported then this method throws an
    * {@link UnsupportedRepositoryOperationException}.
    *
    * @return object
    *   A {@link LockCapabilities} object.
    *
    * @throws {@link UnsupportedRepositoryOperationException}
    *   In level 1: Always.  In level 2: if implementation does not support
    *   locking.
    */
    public function getLockCapabilities();
    
    
   /**
    * If observation is supproted gets the {@link ObservationManager},
    * otherwisein throws an {@link UnsupportedRepositoryOperationException}>.
    *
    * Level 1:
    *
    * Always throws an {@link UnsupportedRepositoryOperationException} since
    * observation is not in supported in level 1.
    *
    * Level 2:
    *
    * If observation is supported (it is optional, even in level 2), gets the
    * {@link ObservationManager} object through which event observation
    * is managed. Otherwise throws an
    * {@link UnsupportedRepositoryOperationException}.
    *
    * @return object 
    *   An {@link ObservationManager} object.
    *
    * @throws {@link UnsupportedRepositoryOperationException}
    *   In level 1: Always.  In level 2: If implementation doesn't support
    *   observation.
    */
    public function getObservationManager();
    
    
   /**
    * Serializes the subtree rooted at the node (it must be a {@link Node}, 
    * not a {@link Property}) at $absPath as an XML document and 
    * saves it to the supplied $out. The resulting XML is in the
    * system view form.
    *
    * If $binaryAsLink is TRUE then any properties
    * of {@link PropertyType::BINARY} will be replaced in the serialized
    * output by properties of {@link PropertyType::SOFTLINK} recording
    * their own absolute path; otherwise the actual value of each 
    * {@link PropertyType::BINARY} property is recorded using Base64
    * encoding.
    *
    * If $noRecurse is TRUE then only the {@link Node}
    * at $absPath and its properties, but not its child nodes, is
    * serialized; otherwise the entire subtree rooted at $absPath
    * is serialized.
    *
    * If the user lacks read access to some subsection of the specified tree,
    * that section simply does not get serialized, since, from the user's
    * point of view, it is not there.
    *
    * <i>PHP Note</i>: PHP does not have an OutputStream, as the Java 
    * specification calls for.  Instead, $out is expected to be a
    * string passed by reference.
    *
    * @param string
    *   The path of the root of the subtree to be serialized.
    * @param string
    *   The string to which the XML serialization of the subtree will be output.
    * @param bool
    *   A boolean governing whether binary properties are to 
    *   converted to soft links.
    * @param bool
    *   A boolean governing whether the subtree at 
    *   $absPath is to be recursed.
    *
    * @throws {@link PathNotFoundException}
    *   If no {@link Node} exists at $absPath.
    * @throws {@link RepositoryException}
    *   If another error occurs.
    */
    public function exportSysView($absPath, &$out, $binaryAsLink, $noRecurse);
    
    
   /**
    * Same as {@link exportSysView()} except that the resulting XML is in the 
    * document view form.
    *
    * @param string
    *   The path of the root of the subtree to be serialized.
    * @param string
    *   The string to which the XML serialization of the subtree will be output.
    * @param bool
    *   A boolean governing whether binary properties are to 
    *   converted to soft links.
    * @param bool
    *   A boolean governing whether the subtree at 
    *   $absPath is to be recursed.
    *
    * @throws {@link PathNotFoundException}
    *   If no {@link Node} exists at $absPath.
    * @throws {@link RepositoryException}
    *   If another error occurs.
    */
    public function exportDocView($absPath, &$out, $binaryAsLink, $noRecurse);
}

